\lstset{ %
language=C,                % choose the language of the code
basicstyle=\footnotesize,       % the size of the fonts that are used for the code
numbers=left,                   % where to put the line-numbers
numberstyle=\footnotesize,      % the size of the fonts that are used for the line-numbers
stepnumber=2,                   % the step between two line-numbers. If it's 1 each line will be numbered
numbersep=5pt,                  % how far the line-numbers are from the code
backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
showspaces=false,               % show spaces adding particular underscores
showstringspaces=false,         % underline spaces within strings
showtabs=false,                 % show tabs within strings adding particular underscores
frame=single,	                % adds a frame around the code
tabsize=2,	                % sets default tabsize to 2 spaces
captionpos=b,                   % sets the caption-position to bottom
breaklines=true,                % sets automatic line breaking
breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
title=\lstname,                 % show the filename of files included with \lstinputlisting; also try caption instead of title
escapeinside={\%*}{*},          % if you want to add a comment within your code
morekeywords={*,...}            % if you want to add more keywords to the set
}

\chapter{PORN-OS User Programs}

\section{Introduction}
PORN-OS comes with a set of User Level Programs (in the following called ULPs).
The User Programs are described below together with instructions on how they can be used. Before attempting to run any of the user programs you must ensure that the instructions provided in "Starting PORN-OS" have been followed and the OS has been built and started correctly.
The ULPs can be started from the shell, which is a ULP itself.
If question about the usage of the OS should arise that are not covered in this report, you are most welcome to ask us using one of the email given on the cover.

\section{shell}
\subsection*{Description:} 
The shell is is intended for primary interaction with the OS. It can be used to start other programs. To get an overview of the commands that can be used in the shell, type \texttt{help} and press enter. A summary of all available commands will be displayed.
To start programs use the command \texttt{start}. The exact syntax of the start command can be viewed using the help command.

Here is an example
\begin{lstlisting}
 start 1 ring 10 5 
\end{lstlisting}

This starts the ring program with priority 1 and the two parameters 10 and 5. The meaning of the parameters is specific to the ULP ring. The priority is an integer number between 1 (highest) and MAX\_PRIORITY (lowest, initially 42).\\

Quickly, the other commands recognized by the shell are:
\begin{itemize}
	\item exit: exits the shell
	\item kill pid code: kills the process pid and returns code to its waiting parent/supervisors
	\item chprio pid prio: changes the priority of the process pid to prio
	\item echo text: prints text to the console
	\item echolcd text: prints text on the Malta LCD
	\item block pid: blocks the process pid
	\item delay pid: delays the process pid
	\item wake\_up pid: wakes the process pid up
	\item wait pid: waits for termination of the process pid (which must be a child of the shell)
	\item pinfo pid: displays information about the process pid
	\item ps: displays information about all processes in the system
	\item help [progname]: if progname is specified, displays the help for this program, otherwise displays the shell's help
\end{itemize}

\section{increment}
\subsection*{Description:}
The program takes one parameter which is interpreted as integer upper bound. The program will then print all natural numbers starting from 1 to the upper bound inclusively. One number is printed per line. This program can be used to check if the uart is working and to pratice the execution of ULPs.

\subsection*{Parameters:} 
\begin{itemize}
 \item \textbf{number}: a positive integer to which the program will print on each line. 
\end{itemize}

\subsection*{Example}
\begin{lstlisting}
start 1 increment 4
\end{lstlisting} 

\section{fibonacci}
\subsection*{Description:}
This program calculates the Fibonacci series and prints it to the screen up to a number given.
The number which provides the break condition for the program can be specified as first parameter after the program name.
\subsection*{Parameters:}
\begin{itemize}
 \item \textbf{maximum\_number}: a positive integer to which the program will calculate the series.
\end{itemize}
\subsection*{Example}
\begin{lstlisting}
start 1 fibonacci 34
\end{lstlisting} 

\section{scroller}
\subsection*{Description:}
The program scrolls a predefined text string on the MALTA LCD display. The string can be of arbitrary length, but only 8 characters can be displayed on the LCD display at one given time. The program can be used to test the functionality of the LCD display. The predefined string is "PORN-OS OR No OS! "

\subsection*{Example}
\begin{lstlisting}
start 1 scroller
\end{lstlisting} 

\section{ring}
\subsection*{Description:}
The program will spawn up a variable amount of children and let these processes exchange a variable amount of messages in a circular way (Ring communication). This program is an implicit test for PORN-OS message passing and scheduling. The amount of children and the amount of messages have to be specified as parameters to the program.

\subsection*{Parameters:}
\begin{itemize}
 \item \textbf{number\_of\_children}: a positive integer containing the number of processes that form the ring. It has to greater than 1.
 \item \textbf{number\_of\_messages}: a positive integer containing the number of messages to be passed among the messages. It has to be at least 1.
\end{itemize}

\subsection*{Example}
\begin{lstlisting}
start 1 ring 2 4
\end{lstlisting} 

\section{eat}
\subsection*{Description:}
The program is a solution to the dining philosopher problem. It implements a waiter-solution where a waiter is added to the table and tells the philosophers whether it is okay or not to take a fork. There is a variable amount of philophers sitting around a table. Every philosopher has a fork lying next to his right and left, but there is only one fork in between two philosophers. The philosophers are represented as processes in the program. They are created, and the waiter as well, at the beginning by the main process, which is initially started. To pick up and release forks the philosophers exchange messages with the waiter. This is another implicit test of PORN-OS message passing.

The amount of philosophers and the amount of cycles (thinking, picking forks, eating, putting forks back) that the philosophers undergo are specified as parameters.
\subsection*{Parameters:}
\begin{itemize}
 \item \textbf{number\_of\_philosophers}: a positive integer that will serve as the number of philosophers
 \item \textbf{number\_of\_cycles}: a positive integer that will represent the number of cycles that the philosophers will go through
\end{itemize}
\subsection*{Example}
\begin{lstlisting}
start 1 dinner 5 3
\end{lstlisting} 

\section{supervisor}
\subsection*{Description:}
The program demonstrates PORN-OS process supervision capabilites. A supervisor process spawns up a variable amount of processes and then waits for supervision messages from the children. The children send messages to the parent and exit after having sent 10 messages. The program quits when the system runs out of memory.
\subsection*{Parameters:}
\begin{itemize}
 \item \textbf{number\_of\_children}: a positive integer that will serve as the number of processes to be spawn.
\end{itemize}
\subsection*{Example}
\begin{lstlisting}
start 1 supervisor 5
\end{lstlisting} 

\section{oom}
\subsection*{Description:}
The program creates processes until the memory is full. No parameters are required for this program. The pid of each child is kept in a linked list that grows dynamically each time fourchette is called. Once the system has run out of memory, it uses this list to kill all the children it has spawned. 

\subsection*{Example}
\begin{lstlisting}
start 1 oom
\end{lstlisting} 


\section{init}
\subsection*{Description:}
This program somewhat differs from a normal User Program because it is automatically started by PORN-OS at startup. Aside from that, this is a perfectly normal User Program. The given init program starts the scroller and a shell. It then restarts the shell each time it dies to make sure there is always a shell active in the system.

% -rwxr-xr-x 1 volker volker  6690 2010-05-27 12:24 count.c
% -rwxr-xr-x 1 volker volker   238 2010-05-20 18:09 supervised_spawn.c
% -rwxr-xr-x 1 volker volker  2214 2010-05-27 12:24 uart_test.c

